part_uniqueidpush

Unique ID Push

Unique ID Push notifications provide the possibility to push specific information to a business partner in the value chain (one level up or one level down). This can help to provide faster information to reduce necessary information collection activities (connect-to-parent) or to provide information that is not available at all at the receiver side (connect-to-child).

The solution is based on notification assets in the EDC (which is the same approach that is used for quality incidents). The notification receiver creates a notification asset in the EDC and the notification sender sends his notifications to this notification asset. As this notification asset is a general EDC asset - as for all EDC assets - access policies, usage policies and contract definitions must be created.

✋ It is important to understand that the receiver creates EDC asset and policies, and thus, the sender of the Unique ID push notification must check during the EDC negotiation process if the conditions the receiver offers are acceptable for the sender.

Currently there are two types of Unique ID Push Notifications available: "Connect to Parent" and "Connect to Child".

Connect to Parent

Unique ID Push notifications of type "connect-to-parent" are a way for a manufacturer to notify a customer as soon as possible when a new digital twin for a part is available.

The sender of the notification is the supplier of a part item and the receiver of the notification is the customer of that part item. The Unique ID of that part is sent in the notification.

Connect to Child

Unique ID Push notifications of type "connect-to-child" are a way for a manufacturer to notify a supplier when the supplier's part has been used (or is to be used in the case of part type) in the assembly or production of the manufacturer's product. This will result in an update of the corresponding SingleLevelUsage aspect at the supplier side.

The sender of the notification is the customer of a part item or type and the receiver of the notification is the supplier of that part item or type. The Unique ID of that part, quantity and dates are sent in the notification.

Connect to Parent and Connect to Child notifications can be applied to Digital Twins for part instances and for part types.

Prerequisites and Constraints

In order to be able to push Unique ID(s) of part(s) to the correct partner, it is required that the sender pushing the Unique ID notification is aware of the BPN of the receiver of the notification or has enough data in its context to use BPDM functions to determine the BPN Number of the receiver.

For actively pushing Unique ID notifications, an EDC is required and the data provider needs to be enabled to execute the complete process including EDC communication and HTTP Push (i.e., HTTP POST) of the payload.

Secondly, EDCs are being used for the exchange and it is currently required to offer a HTTP POST API to receive the Unique ID notifications push at the receiver's side. This API needs to be registered in the EDC Catalog as a data offer and requires specific properties to be set to standardized values, as this allows discoverability. Details still tbd.

Unique ID Push Process Overview

Connect to Parent

How the actual process is triggered is application specific. It is recommended to trigger the push of Unique IDs towards the customer after the Goods Issue has been booked, since commonly at that point the serial numbers/batch numbers of the parts being delivered are fixed in the logistics process and shall be contained in delivery documents, EDI Messages and/or any internal representation of the received items (non-Catena-X communication).

The Unique ID push is initiated by the supplier (acting as sender) towards their customer (acting as receiver). Since the Unique ID of the asset (i.e., serial unit / batch) is unknown in the logistics process, the message needs to include local identifiers to be matched towards the information from the delivery documents and furthermore the internal data of the recipient's traceability solution.

Upon receipt of the message, the customer needs to match the local identifiers with its internal traceability records and attach each Unique ID to the respective data set. How this is done is depending on the customer's internal systems:

• If there is an object for incoming deliveries, this event could be updated. Alternatively, if only production events are tracked, the data could be integrated at this point into the data provisioning pipeline's data structure for consumed materials.
• In the end this enables the customer to integrate the child parts into the SingleLevelBomAsBuilt aspect.

Connect to Child

How the actual process is triggered is application specific. It is recommended to trigger the push of "connect-to-child" towards the supplier earliest after the singleLevelBom aspect (AsBuilt oder AsPlanned) has been created, since at that point all relevant information is available. It is also possible to collect "connect-to-child" notification content at customer side and send this in a list to the supplier, e.g. once a day or once a week.

The Unique ID push is initiated by the customer (acting as sender) towards their supplier (acting as receiver). The body information comes from the corresponding singleLevelBom aspect.

Upon receipt of the message, the supplier needs to update the corresponding singleLevelUsageAspect(s) at his side. All information required can be taken from the body in the notification.

Schema of Unique ID Push Notifications

The Unique ID Push notifications have a standardized format. Schemas of these notifications are described in detail in the Unique ID Push Open API specification. The standardized version of this API is 2.0.0. Version 2.1.0 is not (yet) standardized, but backwards compatible, and extends v2.0.0 with the Connect-to-Child feature.

Connect to Parent

• For the context field in the notification header, use the following string for Unique ID Push notifications as described in this KIT: IndustryCore-UniqueIDPush-ConnectToParent:<API version>.

• Adding the customer part ID to the notification is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part ID for their parts. But, in case the manufacturer knows the customer and the corresponding customer part ID of its part though, it is required to always add the customer part ID to the notification.

Connect to Child

• For the context field in the notification header, use the following string for Unique ID Push notifications as described in this KIT: IndustryCore-UniqueIDPush-ConnectToChild:<API version>.

Notification Receiver

Here is a short overview what the receiver has to do when they want to support Unique ID Push notifications. This is an optional feature.

• Connect to Parent The receiver in this scenario is the customer of a part.
• Connect to Child The receiver in this scenario is the supplier of a part.
• The receiver must create a EDC asset in their EDC that works as the endpoint for receiving notifications. Also, access & usage policies as described below must be configured.
• The EDC in which the notification EDC asset was created must be registered at the EDC Discovery (so that the sender can find the partner's EDC which should receive notifications)
• When the Receiver receives a Unique ID Push notification, it must process this notification after it was received by the EDC (in a Backend Data Service)
• How the Receiver processes the notification is up to them, but the following steps are recommended:
  • Verify the correctness of the data in the notification (i.e., the receiver is actually the customer of this part).
  • Store the notification data for later.
  • Connect to Parent Use this data when the digital twin for the part into which the delivered part is built into is created instead of doing a lookup to a supplier's Digital Twin Registry.
  • Connect to Child Use this data to update the corresponding singleLevelUsage aspect

EDC Asset

For the EDC asset for receiving Unique ID Push notifications, the following properties must be set:

{
  "@context": {
    "edc": "https://w3id.org/edc/v0.0.1/ns/",
    "cx-common": "https://w3id.org/catenax/ontology/common#",
    "cx-taxo": "https://w3id.org/catenax/taxonomy#",
    "dct": "https://purl.org/dc/terms/"
  },
  "@id": "{{ _.assetId }}",
  "properties": {
    "dct:type": { "@id": "cx-taxo:{{ _.notificationType }}" },
    "cx-common:version": "2.1"
  }
}

Properties https://purl.org/dc/terms/type and https://w3id.org/catenax/ontology/common#version are used to classify the asset and are explained in the Digital Twin KIT in more detail.

For {{ _.notificationType }}, use

• UniqueIdPushConnectToParentNotification for the Connect-To-Parent notification asset and
• UniqueIdPushConnectToChildNotification for the Connect-To-Child notification asset.

✋ Note that the API version can be different depending on what Unique ID Push API version your company supports.

EDC Policies

Access Policies A data provider can decide on its own what access policies they want to define for their notification asset. Based on the purpose of the asset, all suppliers of the data provider should in general be allowed to send notifications to this asset. Therefore, either a public access policy or a BPN-based access policy (allowing all suppliers) should be used.

Usage Policies In general, a data provider is free to decide which usage policies to define for its assets. For notifications, though, the data provider is actually the receiver of notifications, i.e., the usage policy here has the purpose to define what the data provider does or is allowed to do with the notifications. It's something the sender of the notification has to rely on and accept when sending its notification.

Keep in mind that usage policies currently aren't technically enforced by the EDC or other components.

✋ Usage Policy for Unique ID Push The Unique ID push notification endpoints are protected with a purpose-based usage policy and "cx.core.industrycore:1" as purpose.

Backend Data Service to Process Unique ID Push Notifications

The receiver must setup a backend data service that provides an HTTP Endpoint for notifications. All endpoints are described in detail in the Unique ID Push Open API specification. The standardized version of this API is 2.0.0. Version 2.1.0 is not (yet) standardized, but backwards compatible, and extends v2.0.0 with the Connect-to-Child feature.

Notification Sender

Here is a short overview what the sender has to do when they want to support Unique ID Push notifications. This is an optional feature.

Connect to Parent (Sender = Supplier)

• The Sender in this scenario is the manufacturer or supplier of a part.
• When a new digital twin for a part was created, the manufacturer is responsible to send a Unique ID Push notification for this twin to the customer of this part.
• It is recommended to send this notification as soon as possible, i.e., directly after the digital twin was created.

Connect to Child (Sender = Customer)

• The Sender in this scenario is the consumer of the supplied part.
• When the supplied part is used in the production or assembly at the customer side, the customer is responsible to send a Unique ID Push notification for the twin of the used part to the supplier of this part. This is known by the customer when the singleLevelBom aspect is created or updated.
• This notification can be sent immediately or collected to be sent when convenient, e.g. once a day or once a week, depending on the use case.

Mapping BPN to EDC URL with EDC Discovery API

Connect to Parent The sender must first find the EDC of the customer (receiver) to which the notification should be sent to. For this, the BPN of the customer is required.

Connect to Child After creating the singleLevelBom aspect the sender should already know the BPN of the supplier (receiver).

With this, the EDC Discovery can be used to query for all EDCs of the receiver. After that, the data catalog of each of these EDCs must be queried for the notification EDC asset as described above. If this notification EDC asset is found in one of these EDCs, the notification can be sent.

There should only be one EDC which provides the notification EDC asset for Unique ID Push. If more than one EDC (for the same BPN/partner) are found, this is considered a misconfiguration of the corresponding partner.